Magnum One

home *** CD-ROM | disk | FTP | other *** search

/ Magnum One / Magnum One (Mid-American Digital) (Disc Manufacturing).iso / d11 / ansipl20.arc / ANSIPLAY.DOC < prev next >

Wrap

Text File | 1991-07-08 | 47KB | 1,159 lines

ANSIPLAY vs. 2.0 - Copyright 1991, J. Ibarra ALL RIGHTS RESERVED U S E R ' S M A N U A L INDEX: PAGE NO. ------------------------------------------- -------- Copyright Notice and Regulations . . . . . . . . 2 Introduction . . . . . . . . . . . . . . . . . . 2 Files included with the program. . . . . . . . . 4 Printing the manual. . . . . . . . . . . . . . . 4 How ANSIPLAY works . . . . . . . . . . . . . . . 5 About ANSI.SYS (and installation). . . . . . . . 5 Editing your ANSI file . . . . . . . . . . . . . 6 Music string syntax. . . . . . . . . . . . . . . 6 Music string contents. . . . . . . . . . . . . . 7 Music codes / Sound codes definition . . . . . . 7 Using Music Codes. . . . . . . . . . . . . . . . 8 Using Sound Codes. . . . . . . . . . . . . . . . 8 Music string Tutorial (TUTOR.BAT). . . . . . . . 10 Making the music strings invisible . . . . . . . 10 Using ESC/Music Note characters during editing . 11 Getting familiar with ANSIPLAY . . . . . . . . . 12 ANSIPLAY command syntax (and options). . . . . . 12 Reinitializing the display screen (ANSIPLAY.CLS) 13 Removing music strings (MUSCSTRP.EXE). . . . . . 13 How ANSIAUTO works (slide-show). . . . . . . . . 14 Running ANSIAUTO . . . . . . . . . . . . . . . . 12 Using PLAY.EXE (music string player/editor). . . 15 Common problems. . . . . . . . . . . . . . . . . 16 Registering ANSIPLAY . . . . . . . . . . . . . . 18 -1- First of all, let me get this over with... COPYRIGHT NOTICE ---------------- All rights to ANSIPLAY and included files are reserved by the author, Julie M. Ibarra, and are protected by United States Copyright Laws. Violators will be held accountable for their actions in a Court of Law and may face financial penalties and/or imprisonment. Users are free to use ANSIPLAY and ANSIAUTO for a trial period of 30 days. If after 30 days you decide to keep the program, you must register your copy by sending the required payment to the author. Failure to register your copy after 30 days is in direct violation of copyright laws. Any alterations to the program files or documentation may only be made for the user's own personal usage of the program, provided that you notify the author in writing of said alterations. The program and documentation may NOT be distributed in altered form. REGISTERED VERSIONS OR BACKUP COPIES THEREOF MAY NOT BE DISTRIBUTED, COPIED, OR SHARED IN ANY WAY, OTHER THAN FOR PERSONAL BACKUPS. You may not network the program, or otherwise use it on more than one computer. If the program is to be used on more than one computer a separate registration is required per computer. Otherwise, non-registered versions of ANSIPLAY (and included files) may be distributed freely in unaltered form provided that NO CHARGE is made for the program itself (postage and disk costs excluded). This product is provided "AS IS" WITHOUT WARRANTY OF ANY KIND. The entire risk as the results and performance of the PRODUCT is assumed BY YOU. In NO event shall the author, nor employees of the author be liable for any damages whatsoever (including without limitation damages for loss of business profits, business interuption, loss of business information and the like) arising out of the use of or inability to use this product even if the author has been advised of the possibility of such damages. INTRODUCTION ------------ If you have this program, more than likely you are already familiar with ANSI control sequences. But just for sake of reference, here's a few more details about what ANSI is and how it works. ANSI (American National Standards Institute) control sequences are simply sets of characters which, when put together, will enable computer-users to have extended control over their display screen. -2- This extended control is given by DOS's device driver, ANSI.SYS, which reads these sets of characters, interprets them, and then processes the commands by moving the cursor positions, changing screen colors, etc. They also will allow your monitor to display the extended ASCII character set (Decimals 128 - 255). These sets of characters are referred to as Escape Command Sequences. In other words, a sequence of commands preceeded by an Escape character (Decimal Character 27). Each computer system processes these command sequences at different speeds...for example, an AT will processes much faster than an XT. There are several software packages which allow the user to edit and save these command sequences into a file (called an ANSI file) without having to know the actual command sequences. Some of these (such as shareware's "TheDraw") will allow you to specify the speed of which you want the ANSI file to be displayed. Once the ANSI.SYS device driver is installed in DOS (Disk Operating System), these ANSI files may be displayed by simply typing a DOS command something like: TYPE FILENAME.ANS Installation of ANSI.SYS is discussed later in this manual. Until now, the ANSI files have had one drawback...they have screen control, but no sound. ANSIPLAY was developed for the purpose of adding music/sound ability to ANSI files. ANSIPLAY is NOT intended to be an ANSI editing program such as the well known shareware program "TheDraw" which enables on-screen selection of colors, cursor positions and movement, etc., but rather ANSIPLAY is intended allow the user to use ANY ANSI file and, by adding a few extra escape command sequences (we'll call them music codes), enable the integration of screen display and music/sound/pauses to it. Once these music codes are added to the file (by use of most any text editor), the simplest command used to display/play them would replace the 'TYPE' command with 'ANSIPLAY', thus something like: ANSIPLAY FILENAME.ANS Later in this manual is a more detailed breakdown of command syntax and additional options available with ANSIPLAY. One thing to remember: Adding music strings to the file is kind of like putting icing on the cake...it's the final touch to your ANSI file. You can't re-bake the cake once the icing's been put on it, and you can't reconstruct the ANSI file with an ANSI editor -3- (such as "The Draw") with the music strings in it. The reason being that the editor will try to interprete the escape sequences containing music strings as text, therefore displaying it to screen. You CAN however, remove the music strings using MUSCSTRP.EXE, to make the file compatible for the ANSI editor again (refer to the section on "Removing Music Strings"). A text editor, of course will interprete ALL characters as text so there's no problem there. FILES INCLUDED -------------- Files included with this package are as follows: ---Program Files--- ANSIPLAY.EXE - Program to read/display/play ANSI files. ANSIAUTO.EXE - Program to automate ANSIPLAY.EXE into a slide-show. PLAY .EXE - Allows you to play a music string from the DOS prompt. MUSCSTRP.EXE - Removes music strings from your ANSI files. GO .BAT - An Introduction to the entire program package. TUTOR .BAT - A brief tutorial on some of ANSIPLAY's more advanced features. (Read this manual first.) ---Documentation--- OVERVIEW.DOC - A quick look at most of ANSIPLAY's features. ANSIPLAY.DOC - User's Manual (This documentation). ANSICODE.TXT - Listing of ANSI control sequences available. MUSICODE.TXT - Listing of Music codes available to be used with ANSIPLAY.EXE. (Also see the section on Sound Codes). ORDER .FRM - Registration Form to purchase your registered and most current version of ANSIPLAY. ---Data Files--- ANSIAUTO.DAT - Sample Data file used with ANSIAUTO.EXE. INTRO .ANS - Data file used with GO.BAT TUTOR .ANS - ANSI file used with TUTOR.BAT XMASTREE.ANS - Demonstration ANSI file (using music codes) FAUCET .ANS - Demonstration ANSI file (using sound codes) SEA .ANS - Demonstration ANSI file (using music and sound codes) PRINTING THE MANUAL ------------------- If you wish to print the manual, log onto the same drive/directory in which this file (ANSIPLAY.DOC) exists, and type COPY ANSIPLAY.DOC PRN at the DOS prompt. -4- All other documentation files/order form may be printed the same way by using different filenames. HOW ANSIPLAY WORKS ------------------ When you run ANSIPLAY, you will specify the filename of the file you want to be displayed/played. ANSIPLAY will read the file and display it to the screen using the ANSI.SYS device driver, while at the same time, searching for music codes which tell ANSIPLAY what music notes/sounds to play. The music codes are NOT ANSI escape command sequences, but rather they are interpreted and processed by ANSIPLAY. ANSIPLAY will be just slightly slower than DOS's TYPE command since it must search the text for each music string and process it accordingly. DOS's TYPE command will process the strings as text. The text may be made hidden (invisible) by embedding additional escape command sequences in the ANSI file. (Refer to the section on "Making the music strings invisible".) Shareware versions will then display a short message in ANSI to remind users that the version in not registered. This message is not displayed with registered versions. ABOUT ANSI.SYS (DEVICE DRIVER) ------------------------------ Many programs use ANSI control characters, but if the device driver ANSI.SYS is not installed before comming accross them, you'll just get a lot of funny looking characters that don't mean much. The ANSI.SYS device driver is included in your own DOS files. If you're wondering whether or not your system has ANSI.SYS already installed, you can type 'ANSIPLAY' at the DOS prompt. When the copyright message is displayed, if you see color, the driver is installed. If you get a menagery of strange characters on the screen, ANSI.SYS is NOT installed. HOW TO INSTALL ANSI.SYS ----------------------- DOS's ANSI.SYS device driver only needs to be installed once. This is done by creating (or editing an existing file) a file called CONFIG.SYS which must be in the root directory of the disk from which your computer boots from. If you want to create a new CONFIG.SYS file, use the following commands, BEWARE however that if the CONFIG.SYS file already exists and you use the following commands, the existing file will be overwritten... 1. At the DOS Prompt type COPY CON C:\CONFIG.SYS (wherein C: should be changed to the name of your bootable disk drive) -5- 2. You will not get a new DOS prompt after this command. Now type DEVICE=C:\DOS\ANSI.SYS (followed by [ENTER]), (wherein C:\DOS should be changed to the name of the disk drive\directory in which the file ANSI.SYS exists.) 3. To exit the COPY CON command, type [CTRL]+[Z] and [ENTER]. You should now be returned to the DOS prompt. ANSI.SYS will now be installed automatically each time your computer is booted. 4. To reboot, you can type [CTRL]+[ALT]+[DEL]. Hold down the [CTRL] key, then hold down the [ALT] key, then hit the [DEL] key and let go. If you have an existing CONFIG.SYS file that must be edited, you can use a word/text editor, or consult your DOS user's manual on how to use DOS's text editor EDLIN.EXE. EDITING YOUR ANSI FILE ---------------------- If you are starting from scratch, you may want to look into an ANSI screen editor such as the shareware program "TheDraw". Without such a program, ANSI file creation can be tackled, but it would be extremely tedious and time-consuming at best. Your DOS user's manual will explain the escape control sequences used with ANSI.SYS. There is also a reference listing included in the file ANSICODE.TXT (see section on "printing the manual"). One example would be, to set the foreground color to bright yellow on a blue background... ESC[44;1;33m Unless you're very familiar with these escape sequences, it can be a bit like learning a foreign language. MUSIC STRING SYNTAX ------------------- Once your ANSI file has been created, all that's left to do to make it musical is add a few extra escape command sequences, for example, a music code of... ESC[MF O2 CDEC CDEC EFG.... EFG....(music note) would play the introduction to the song "Frere Jacques". Below is a breakdown of how the music strings are to be used. By using your own text editor, you can insert these codes into any desired location in your ANSI file, then play it back using ANSIPLAY.EXE. (see section below on using ESC character during editing) -6- MUSIC STRING CONTENTS --------------------- The word "string" simply means a set of characters (including spaces and ascii characters) strung together. There are 3 sections to a Music string, broken down as follows: ESC[MF CDEC CDEC EFG (music note) ------ ------------- ------------ 1 2 3 All music strings must be prefixed with ESC+"["+"MF" (or "MB") in upper-case text, and final character must be a (music note). 1. Music strings are prefixed with the ESCape character followed by a [ character (just like ansi escape control sequences), and then followed by MF (for Music/Sound to be played in Foreground) or MB (for Music to be played in Background). *Or for a shortcut you may use ESC[M which will be treated as ESC[MF. *** Note that the ESC above actually resembles the ESCAPE character (Decimal CHR$(27)) and not the actual letters E S C. Refer to the section on "Using the ESC character during editing". 2. The middle part of the string can be 1 of 2 types of commands... Music Codes ----------- a) the actual <notes, octaves, etc> specification (for musical tunes). Spaces and carraige returns (CR-LF) are ignored. This portion of the music string can be of any size length. -or- Sound Codes ----------- b) a <tone frequency; duration; cycles; delay; vari> specification (for other sound tones and repeated cycles of sound tones). Parameters must be separated by semi-colons. Details on these codes and command syntax will be discussed shortly. There is also a reference listing of the codes in the file MUSICODE.TXT (see section on "printing the manual"). 3. The final(music note) (Decimal CHR$(14)) is a must. This tells ANSIPLAY where the music string ends. The (music note) character can be entered on most text editing programs by holding down the [ALT] key, then typing the number 14...similarly to entering the ESC character. (See "Using the ESCape character during editing") -7- ------------------------------- USING MUSIC CODES ------------------------------- ESC[MF <music notes and commands)> (music note) (MB may be used in place of MF) Example: ESC[MF CDEC CDEC EFG (music note) MF will play the music in the foreground, or in other words will stop displaying temporarily until the music string is played completely. MB will place the music string into a buffer, allowing the program to execute while the music string is playing in the background. The number of notes that can be played in the background at one time varies according to the particular machine. Maximum number of notes that can be played in the background at one time is 32. When there are more notes to be played than the buffer will hold, the display will temporarily pause until the remainder of the music string is processed. More than 1 MB statement in the music string will cause the music to be played sequentially (NOT simultaneously.) In other words, you cannot play 2 or 3 strings of music simultaneously. If a carraige return (CR-LF) is needed within the music string, ANSIPLAY will ignore it and just continue playing. This feature was developed so that user's could use L-O-N-G strings of music without interruption. A breakdown of MUSIC CODES available are listed in the file MUSICODE.TXT. (refer to section on "Printing the Manual"). You may also consult your DOS user's manual under the section on BASIC's "PLAY" statement. See the demonstration ANSI files included with this package for some examples of how MUSIC CODES may be used. ----------------------------------------------- USING SOUND CODES (IN PLACE OF MUSIC CODES) ----------------------------------------------- In place of music codes, you may use numeric values for FREQENCY, DURATION, CYCLES, DELAY and VARIATION to create sounds that are not available with musical code syntax. The music string would look like this: ESC[MF <FREQ; DURA; CYCLES; DELAY; VARI> (music note) Example: ESC[MF 100;5;5;10;-5 (music note) -8- The <> brackets are not to be typed. They are only there for display purposes to you can see where the <SOUND CODES> are to be placed. Since SOUND CODES are processed differently from MUSIC CODES, SOUND will always be played in foreground regardless of "MF" or "MB" specification. SOUND CODE Parameters must be separated by semicolons. Minimum/Maximum values and descriptions are as follows: FREQUENCY : a numeric value from 37 to 32,767 Frequency is the desired frequency in hertz. This allows more control over the pitch of the tone than what is available with music codes. DURATION : an numberic value from 0 to 65,535 Duration is how long the tone should play, measured in clock ticks. There are 18.2 clock ticks per second regardless of CPU speed. CYCLES (optional) : an integer from 0 to 9,999 Cycles is the number of times to repeat the frequency/duration. DELAY (optional) : an integer from 0 to 999,999,999 Delay is the length of pause between cycles. ANSIPLAY will count from 0 to DELAY before proceeding. The DELAY time lapse will vary among computer systems. (My XT NEC V20 averages 723 counts per second) If the [ENTER] key is hit during execution of a DELAY, the delay will be ended. VARIATION (optional): an numeric value from -9,999 to 9,999 Variation will change the FREQUENCY each time the tone is repeated using the CYCLES variable. FREQUENCY will use it's current value, add the VARIATION value to itself (per cycle) to get a new FREQUENCY, then play the new FREQUENCY. A negative value used for VARIATION will make the FREQUENCY decrease; a positive value will make the FREQUENCY increase. If the new FREQUENCY is too low or too high, exceeding its playable limits (minimum of 37 to maximum 32,767) then the VARIATION value will be changed to reverse itself (from positive to negative, or from negative to positive). A "*" wildcard may be used in place of a value, which will make the play function select a value at random between -999 and 999. Any non-integer numbers used for CYCLES or DELAY will be converted to integers automatically. -9- SOUND CODES are interpreted and executed as they are read, therefore requiring them to be played in the foreground. The interpretation process is basically structured like this: :START_OF_CYCLE Play Frequency/Duration Add DELAY if applicable Change Frequency if VARIATION is used Go to :START_OF_CYCLE (Loop for number of CYCLES specified) See the demonstration ANSI files included with this package for some examples of how SOUND CODES may be used. TUTORIAL FOR MUSIC STRINGS ------------------------- Now that you are somewhat familiar with music code and sound codes...you can see a more detailed explaination of some of the more advanced way in which these codes can be used by typing TUTOR at the DOS prompt. This will ansiplay the file TUTOR.ANS which will give some examples and define how they are used. Then it will bring you into ANSIAUTO to display the demonstration ANSI files which are included with the program package. MAKING THE MUSIC STRINGS INVISIBLE ---------------------------------- Since the music strings are interpreted by ANSIPLAY while the file is being read, the music string text is not displayed to the screen. However, if you also wish to not display the strings while using DOS's TYPE command to view the file, this may be done by adding a few extra ANSI escape command sequences. Before the music code, add: --------------------------- ESC[0m ESC[s ESC[?;1H ESC[8m (text is upper/lower-case sensitive) Spaces should not be typed...they are only here to make the codes easier to read. Here is the breakdown: ESC[0m Turns all attributes off. If the display is in high intensity mode, this is required. ESC[s Store the current cursor position. ESC[?;1H Wherein ? is the current row. Any row from 1-24 may be used, however if the cursor has to move all the way across the display, it may cause blinking. 1 sets the cursor at column 1. Even though the text will be invisible, it will still be printed to -10- screen. If the end of screen is reached, the text will be wrapped around to the next row. If you are using long music strings and it is causing the display to eject upward, you may try using shorter strings of about 75 characters or so at a time. ESC[8m This will make the music string invisible when it is written to screen. Otherwise it will be written to screen in the current color attributes. After the music code, add: -------------------------- ESC[u ESC[0m (text is upper/lower-case sensitive) Spaces should not be typed...they are only here to make the codes easier to read. Here is the breakdown: ESC[u Moves the cursor back to the location it was at when the last ESC[s command (store cursor) was used. ESC[0m Returns to normal mode. Turns off invisible attribute. The entire set of commands would look like this... ESC[0m ESC[s ESC[?;1H ESC[8m ESC[MF<music string> (music note) ESC[u ESC[0m Remember, making the music codes invisible is only necessary if you wish to use an ANSI display program other than ANSIPLAY. USING THE ESCAPE CHARACTER DURING EDITING ----------------------------------------- If you use DOS's edlin command for text editing, you will not be able to enter an ESCape character (ASCII character CHR$(27)), since hitting ESCape will type a \ character instead. Most word/text editing programs will allow you to enter an ESCape character by holding down the [ALT] key, then simultaneously entering the number 27. Usually this is displayed as a left arrow character. (Music note would be [ALT] + 14). If you use a commercial word processor such as Word Perfect or Word Star, the text must be saved as plain ASCII text format. Otherwise there will be extra printer codes embedded into the file which will mess up the whole thing. If you do not have a text editor, I recommend a shareware program called QEDIT. It's very powerful and does allow extended ASCII characters. -11- The (music note) character may be entered the same way as the ESCape character by using the decimal 14 instead of 27. GETTING FAMILIAR WITH ANSIPLAY ------------------------------ To see the demonstration files, at the DOS prompt type DEMO. To get familiar with the program and included files, type GO. RUNNING ANSIPLAY ---------------- Syntax from the DOS prompt is as follows: ANSIPLAY [FileName DelaySeconds] [/Option Flags] Parameters are: [Filename] is the drive\path\filename of the ansi file you wish to display/play. Wildcard characters * and ? are not supported. If no filetype is given, then ANSIPLAY will append the filetype of ".ANS" to the filename. If no drive\path is given, then ANSIPLAY will search the currently logged (default) drive\path for the ANSI file. [ DelaySeconds] is the number of seconds to delay program execution. This option is used for ANSIAUTO (automatic slide show present- ation of ansi files). If this option is used, the number of seconds must be preceeded with a space ( ). While using ANSIAUTO, there will be a pause of DelaySeconds between displays of ANSI files. [Options] are as follows: <Multiple option flags may be used in any order> /C (ClearScreen) clears the screen before displaying the ANSI file. /Q (Quiet) Disables the music during display of the ANSI file. /D (Delete) Prompts user if ANSI file is to be deleted after display. This option was designed for those who use off-line mail readers. The mail read can save the message to a temp- orary file, and then Shell out to DOS to ANSIPLAY it. Then the /D option will allow you to delete the temporary file. If you want the freedom to use the ANSIPLAY command while logged onto any drive\directory, just add the name of the directory in -12- which ANSIPLAY exists to DOS's search PATH. (Consult your DOS user's manual for more information on how to do this). Once the file is in process of displaying, hitting ESC will NOT allow you to exit the display until to display is completely processed. The purpose of this is two-fold. First, to allow a bulk read/write of the file thus making the fastest display possible. Second, to avoid stopping the display when the screen may be set in the middle of some strange color combination. (However, ANSIAUTO will exit after the display/play is completed. REINITIALIZING THE DISPLAY SCREEN (ANSIPLAY.CLS) ------------------------------------------------ Once ANSIPLAY has completed displaying/playing the ANSI file, there may have been several changes made to the screen display such as screen mode, color attributes, etc. To reinitialize the display to your desired settings, simply create a file called ANSIPLAY.CLS containing the desired ANSI escape command sequences. ("CLS" for "Closing Screen") This file is optional. If ANSIPLAY.CLS file does not exist, then the only reset code which is automatically executed is ESC[0m which turns all attributes off and returns to normal display. If the file ANSIPLAY.CLS does exist, the ESC[0m will be ignored regardless of whether the file contains escape command sequences or is empty. An example of how this file might be used is to: ESC[=3l 'reset the screen mode to 80 x 25 color ESC[0m 'all attributes off, normal display ESC[44;1;33m 'set colors: bright yellow on blue background ESC[2J 'clear screen thus the contents of ANSIPLAY.CLS would actually be: ESC[=3lESC[0mESC[44;1;33mESC[2J (ESC resembles the actual ESCape character which must be used). Refer to the files ANSIPLAY.DOC and ANSICODE.TXT for more details on the actual ANSI codes to use. It is recommended that no other text, music codes, etc. are included in this file, since they will be displayed after each ANSI file display. REMOVING MUSIC STRINGS (MUSCSTRP.EXE) ------------------------------------- If wish to remove all existing music strings from the ANSI file, at the DOS prompt type MUSCSTRP FILENAME.ANS -13- MUSCSTRP (Music Strip) will create a new file using the same filename, but with the file extension of .NEW The MUSCSTRP program must be able to locate ANSIPLAY.EXE either in the current directory, or in DOS's PATH setting. HOW ANSIAUTO WORKS ------------------ ANSIAUTO will read the contents of the data file you specify on the command line. (See "RUNNING ANSIAUTO" regarding DataFile Structure) Once the data is loaded into memory, ANSIAUTO will shell to DOS and execute the ANSIPLAY command (with any optional parameters which are specified) per file. Each file will be displayed (played) in sequence. If a DelaySeconds parameter was specified, the program will pause after the file is displayed for the set number of seconds, and then continue onto the next file. Once all the files have been displayed, ANSIAUTO will start the sequence over again (and again...). RUNNING ANSIAUTO ---------------- Syntax is as follows: ANSIAUTO DRIVE\PATH\FILENAME.DAT If no filetype is given, then ANSIAUTO will append the filetype of ".DAT" to the filename. To EXIT ANSIAUTO, hit the ESCape key on the keyboard. ANSIPLAY will not respond until the file display/play is completed. At that time, the program will exit and return to DOS. Data file structure ------------------- Each line of the file contains the same specifications as would normally be entered on the DOS command line when executing ANSIPLAY. An example datafile might look like this: C:\ANSI\MERMAID.ANS,3 /C D:\DRAW\CASTLE.ANS,2 /C C:\UTILS\FIREMAN.ANS /C /Q . . . . . . etc. etc. etc. As mentioned before, unregistered versions of the program will display the "ANSIPLAY [Unregistered Version] Copyright 1991, J. Ibarra" message after each file is display/played. Registered versions do not have this message. Maximum number of files that can be used for slideshow is 30. If the data file contains more than 30 filenames, they will be ignored. If 30 is not enough, let me know and I can increase it. -14- USING PLAY.EXE (Music String Player/Editor) ------------------------------------------- Syntax is: PLAY <* MUSIC STRING> (Plays Music Codes or Sound Codes) or: PLAY /E <* MUSIC STRING> (To activate music string editor) If you want to experiment with music/sound codes, PLAY.EXE is the quickest way to do it. PLAY.EXE has two ways of working... 1: It will allow you to play music codes directly from the DOS prompt. 2: It will allow you to edit, then play, the re-edit, etc. music strings, and write to file. * MUSIC STRING is a little different with PLAY.EXE: The prefix of ESC[ and suffix of (music note) are not required on the DOS command line. If MF or MB is not specified, default is set for MF. See sections on "Using Music Codes" and "Using Sound Codes" for more information on Music String Syntax. --- TO PLAY THE MUSIC CODES DIRECTLY FROM THE DOS PROMPT --- Playing a music/sound codes directly from the DOS prompt is easy. An example would be, to hear the beginning of Frere Jacques (ESC[MF O2 CDEC CDEC EFG.... EFG....(music note)), at the DOS prompt, you would type the command line: PLAY O2 CDEC CDEC EFG.... EFG.... or to hear a bomb dropping, you might type: PLAY 900;1;120;;-5 Note that the > and < characters cannot be used from the DOS prompt because DOS will interprete these as piping character. Optionally you can set the octave with On wherein n is the value (0-6) of the Octave you desire. Default octave is 4. Before playing the music string, PLAY.EXE will check for any letters that are NOT valid music code characters. If an invalid letter is found, you will receive the error message "Illegal play string". Play will then take you directly into the music string editor. If the string has a length greater than 73 characters, the string will be trimmed to 73 characters so that it will fit into the editor. If this happens, a message will appear to notify you. --- TO USE THE MUSIC STRING EDITOR --- The music string editor is the more useful feature of PLAY.EXE. It will allow you to play Music Codes or Sound Codes, then edit them on the screen, replay them, etc. Once you have the music/sound codes exactly as you want them, you can then save them to file. -15- The /E option will activate the editor. At the DOS prompt, you may optionally enter the music string you wish to edit . Music String Editor commands are as follows: Move Cursor: LEFT/RIGHT arrow keys Delete Character above cursor: DEL key Move cursor to 1st character: HOME key Move cursor to end character: END key Erase entire music string: CTRL+Backspace Write music string to file: CTRL+W Toggle prefix of "MF" or "MB": TAB key Exit PLAY.EXE: ESC key If the music string contains characters which cannot be played, you will receive an error message "Illegal play string". It will then return to the editor so you can make your changes. The write option will write the music string to a file named "PLAY.MUS". The ESC[MF prefix and (music note) character suffix will automatically be added. If there are pre-existing music strings, the new music string will be appended (not overwritten). COMMON PROBLEMS WITH MUSIC STRINGS ---------------------------------- Problem: I keep getting the error message "Illegal string in PLAY parameters". Solution: Consult the documentation to be sure the values used in your MUSIC CODEs and/or SOUND CODEs are valid. If the problem still persists, and the parameters are indeed valid, contact the programmer. Another Solution: It's possible that the letter O was used in place of the number 0 (zero), or visa-versa in the MUSIC CODE's and/or SOUND CODE's. It's very easy to mix these up. Another Solution: It's possible that the music note characters, [CHR$(14)] was not included in the music string. Consequently, the program will read the entire file until it encounters the music note. If no music note is found, it will append a music note at the end and try to play the string. Problem: Why do I get an "Illegal play string" error? Reason: Something in the play string is not valid. This could be caused by using a note that does not exist such as -16- B#, H, etc.; or using a value which is not within set limits for octave, tempo, etc. such as O7; or using an invalid character which is not a music code/sound code character. Problem: My text editor will not allow me to enter the ESCape char- acter (or music string character) into the ANSI file. Solution: Some editors (though few) do not have this ability. Refer to the section "Using the ESC character during editing". If this still doesn't help...if your editor has a cut-and-paste feature, you might try duplicating the ESC character this way. If all else fails, try another editor. Shareware has a fantastic and very intelligent text editor called "QEDIT". COMMON PROBLEMS WITH USING ANSIPLAY ----------------------------------- Problem: Lots of strange characters (garbage) on the screen. Solution: Be sure that the ANSI.SYS driver is installed into your CONFIG.SYS file (See section on "About ANSI.SYS"). Problem: The program ignores my efforts to escape during the displaying of my ANSI file. Reason: ANSIPLAY reads and processes large portions of the ANSI file at a time. The output of these portions may be as large as the whole display screen. Since the printing of these portions cannot be interrupted, ANSIPLAY will not respond to using the ESCape key. ANSIAUTO, however, will respond AFTER the file display is completed. Problem: When I use "MB" (Music Background) in the music string, there isn't much difference from "MF". Reason: There are several things happening here...For one, ANSIPLAY must pull out the music strings from the bulk of the file which is being read at one time. The strings must then be processed to produce music/sound/pauses. Secondly, the computer's music buffer will only retain 32 characters at a time. If the music string is larger than 32 characters or if the music buffer is full when the new music string is to be loaded into it, the program has to wait -17- for the buffer to process the characters which have already been loaded to free up more space in the buffer for the remaining characters to be loaded. Thirdly, Sound codes that have parameters for CYCLES and/or DELAY are processed counting from 0 to CYCLES (or 0 to DELAY). The counting procedure is not loaded into the background buffer. When the frequency/duration is played, however, it is then placed into the buffer. The counting feature is extremely fast, but if the set values for these parameters are high, it will slow up the display process slightly. Problem: My file was fine until I edited it...now I get a bunch of garbage when displaying it. Solution: Some word processing programs will add extra printer codes to the file when you "save" the file. Most programs that do this also have an option to "save" as "ASCII" or "DOS TEXT". If so, re-save the file using this option. This will save the contents of the file without adding any other embedded program codes. COMMON PROBLEMS WITH USING PLAY.EXE ----------------------------------- Problem: When I tried to write the music string to file, I keep getting an error..."Unable to save". Reason: There may be one of several causes for this: Disk media format error, not enough disk space or disk write-protected to name a few. REGISTRATION OF ANSIPLAY ------------------------ Users who register their copy of ANSIPLAY will receive a new copy of the most current version of the program and included utilities. In addition, registered versions will NOT interrupt the ANSI display with the copyright message at the bottom of the screen. Registered users will automatically be notified when an updated version is released. Registered users will receive a 25% discount on the purchase of any updated version (plus postage and handling). If you wish to register your copy, you may print the registration form by typing COPY ORDER.FRM PRN at the DOS prompt. Fill out the registration form and enclose required payment in check or money order (no cash please) and mail to: -18- Julie M. Ibarra P.O. Box 710727 Santee, CA 92072-0727 To print the registration form, at the DOS prompt, type: COPY ORDER.FRM PRN Any comments regarding program features, documentation, presentation, etc. are also appreciated. Any questions, comments, correspondence may also be directed to the above address. --end of documentation--